Skip to content

Honor HTTP/HTTPS proxy env vars in Hub (#53)#57

Merged
nyo16 merged 1 commit into
masterfrom
bugfix/http-proxy-support
Jun 13, 2026
Merged

Honor HTTP/HTTPS proxy env vars in Hub (#53)#57
nyo16 merged 1 commit into
masterfrom
bugfix/http-proxy-support

Conversation

@nyo16

@nyo16 nyo16 commented Jun 13, 2026

Copy link
Copy Markdown
Owner

Closes #53

Problem

LlamaCppEx.Hub makes its HuggingFace requests through ReqFinchMint.
Unlike curl/wget/requests/Go, Mint does not read proxy environment
variables
. On a proxy-only network every request goes direct and times out:

** (Req.TransportError) timeout
** (MatchError) no match of right hand side value: {:error, "network error: timeout"}

Fix

Add a proxy_request_options/2 resolver that builds Mint connect_options and
wire it into all four Req.get call sites (search, list_gguf_files,
get_model_info, and the streaming download).

A proxy is resolved from, in order:

  1. The :proxy option — a URL string, a Mint {scheme, address, port, opts}
    tuple, or false to disable.
  2. Standard environment variables — HTTPS_PROXY/HTTP_PROXY (and their
    lowercase forms) take precedence over ALL_PROXY, so a usable HTTP proxy
    always wins over an unusable SOCKS one.

Other behavior:

  • NO_PROXY / :no_proxy host bypass — exact, .suffix, and *.
  • Basic-auth from user:pass@ userinfo → proxy-authorization header
    (credentials redacted in logs).
  • Since HuggingFace is HTTPS, the HTTPS_PROXY value applies and tunnels via
    the CONNECT method.
# honored automatically
export HTTPS_PROXY=http://127.0.0.1:8118

# or per call
LlamaCppEx.Hub.search("qwen3 gguf", proxy: "http://user:pass@127.0.0.1:8118")
LlamaCppEx.Hub.download("org/model", "model.gguf", proxy: false)

SOCKS is not supported (by design)

The underlying stack (Req → Finch → Mint) supports HTTP/1 proxies only
plain forwarding and HTTPS-over-CONNECT. There is no SOCKS support anywhere in
Mint/Finch, so a socks5:// value (e.g. from ALL_PROXY) is detected and
skipped with an actionable warning. To use a SOCKS upstream, run a local
HTTP-to-SOCKS bridge (Privoxy, gost) and point HTTPS_PROXY at it. This is
documented in a new "Proxies" section in the module doc.

The original reporter's proxy is 127.0.0.1:8118 — Privoxy's default port —
i.e. they already run an HTTP→SOCKS bridge. With HTTPS_PROXY now honored and
winning over the SOCKS ALL_PROXY, their setup works as-is.

Tests

  • 20 new TDD unit tests in test/hub_proxy_test.exs (env detection, precedence,
    NO_PROXY, basic-auth, SOCKS skip, default ports, scheme-less URLs).
  • Full suite: 158 passed, 4 skipped, 7 excluded.
  • mix compile --warnings-as-errors and mix format --check-formatted clean.

LlamaCppEx.Hub uses Req -> Finch -> Mint, which (unlike curl/wget) does not read proxy environment variables. On proxy-only networks every HuggingFace request went direct and timed out.

Add proxy_request_options/2, resolving a proxy from the :proxy option (URL string, Mint {scheme, host, port, opts} tuple, or false) or the standard env vars: HTTPS_PROXY/HTTP_PROXY (and lowercase) take precedence over ALL_PROXY, with NO_PROXY/:no_proxy host bypass. Supports basic-auth userinfo (redacted in logs). Wired into search, list_gguf_files, get_model_info, and the streaming download.

SOCKS proxies are detected and skipped with an actionable warning, since Mint supports HTTP/1 CONNECT proxies only; documented in a new Proxies moduledoc section with the Privoxy/gost bridge workaround.

Adds 20 TDD unit tests in test/hub_proxy_test.exs.
@nyo16 nyo16 merged commit 85d2880 into master Jun 13, 2026
4 checks passed
@nyo16 nyo16 deleted the bugfix/http-proxy-support branch June 13, 2026 16:03
nyo16 added a commit that referenced this pull request Jun 16, 2026
Update the vendor/llama.cpp submodule from 597b6672e (b9621) to 74ade5274
(b9672), 51 commits. No NIF changes required: every header the binding
compiles against (include/llama.h, ggml.h, ggml-backend.h, common/chat.h,
speculative.h, json-schema-to-grammar.h, sampling.h, common.h) is unchanged.

Verified end-to-end against the freshly built NIF: 158 tests + 7 smoke
tests pass (generation, streaming, chat templates, JSON-schema grammar,
raw GBNF, embeddings), formatting clean, Dialyzer 0 errors.

Also backfill the missing v0.8.25 CHANGELOG entry (Hub HTTP/HTTPS proxy
support, #57), which shipped as a tag without a changelog/version bump,
and advance @Version 0.8.24 -> 0.8.26 accordingly.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

http_proxy required

1 participant